<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Acconeer API: Distance Peak Detector</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">Acconeer API
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('distance_peak.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Distance Peak Detector </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The Distance Peak detector provides an api to get the distance to one or several objects in front of the sensor. It is implemented on top of the Envelope service and data from the Envelope service is further processed to find the peak of the signal.</p>
<div class="image">
<img src="RSS_stack.png" alt="RSS_stack.png"/>
</div>
<p>The figure below show envelope data with two objects in front of the sensor. The Distance Peak detector use algorithms to find the peaks of the two objects and return distance and amplitude to the client. Note that the absolute distance to an object is affected by integration of the sensor behind different material and lenses. For more details on the envelope data it is recommended to use our exploration tool. Check it out on <a href="https://github.com/acconeer/acconeer-python-exploration">github, https://github.com/acconeer/acconeer-python-exploration</a>, <a href="https://github.com/acconeer/acconeer-python-exploration">https://github.com/acconeer/acconeer-python-exploration</a>.</p>
<div class="image">
<img src="envelope_profile_1.png" alt="envelope_profile_1.png"/>
</div>
<p>Acconeer provides an example of how to use the envelope service: <a class="el" href="example__detector__distance__peak_8c.html">example_detector_distance_peak.c</a></p>
<h2>Initializing the System</h2>
<p>The Radar System Software (RSS) must be activated before any other calls are done. The activation requires a pointer to an <a class="el" href="structacc__hal__t.html" title="This struct contains the information about the sensor integration that RSS needs. ...">acc_hal_t</a> struct which contains information on the hardware integration and function pointers to hardware driver functions that are needed by RSS. See chapter 4 in the document “HAL Integration User Guide” for more information on how to integrate to the driver layer and populate the hal struct.</p>
<p>In Acconeer’s example integration towards STM32 and the drivers generated by the STM32Cube tool, there is a function acc_hal_integration_get_implementation to obtain the hal struct.</p>
<div class="fragment"><div class="line"><a class="code" href="structacc__hal__t.html">acc_hal_t</a> hal = <a class="code" href="acc__hal__integration_8h.html#a8b93eb4abdb9ad75250ca6404e0b412d">acc_hal_integration_get_implementation</a>();</div><div class="line"></div><div class="line"><span class="keywordflow">if</span> (!<a class="code" href="group__RSS.html#ga478a45b4920777d3d4fc0f5fc8d05b58">acc_rss_activate</a>(&amp;hal))</div><div class="line">{</div><div class="line">        <span class="comment">/* Handle error */</span></div><div class="line">}</div></div><!-- fragment --><p>The corresponding code looks slightly different in software packages for the Raspberry Pi and other software packages from Acconeer where peripheral drivers for the host are included. The driver layer is first initialized by calling acc_driver_hal_init. The hal struct is then obtained with the function acc_driver_hal_get_implementation.</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (!acc_driver_hal_init())</div><div class="line">{</div><div class="line">        <span class="comment">/* Handle error */</span></div><div class="line">}</div><div class="line"></div><div class="line"><a class="code" href="structacc__hal__t.html">acc_hal_t</a> hal = acc_driver_hal_get_implementation();</div><div class="line"></div><div class="line"><span class="keywordflow">if</span> (!<a class="code" href="group__RSS.html#ga478a45b4920777d3d4fc0f5fc8d05b58">acc_rss_activate</a>(&amp;hal))</div><div class="line">{</div><div class="line">        <span class="comment">/* Handle error */</span></div><div class="line">}</div></div><!-- fragment --><h1>Configuring the Distance Peak Detector</h1>
<p>To use the Distance Peak Detector, first a configuration must be created. To create a configuration, call the acc_detector_distance_peak_configuration_create function which will create a configuration and return it.</p>
<div class="fragment"><div class="line"><a class="code" href="group__Distance__Peak.html#ga3d747e79d0b7aca215d412c2ca578bd0">acc_detector_distance_peak_configuration_t</a> distance_configuration;</div><div class="line"></div><div class="line">distance_configuration = <a class="code" href="group__Distance__Peak.html#ga2176a40e97e051db81b9ca5819d0e836">acc_detector_distance_peak_configuration_create</a>();</div></div><!-- fragment --><p>A newly created configuration is populated with default parameters and can be used directly to create the detector by calling the acc_detector_distance_peak_create function. A more common scenario is to first modify some of the configuration parameters to better fit the application.</p>
<h2>Setting Sweep Parameters</h2>
<p>The base configuration parameters determine the sensor id and how the sweep data will be generated in the sensor. The base configuration parameters are common to all services and are also possible to set in the Distance Peak detector. Like other configuration parameters, the sweep parameters have reasonable default values, but in most applications, it is necessary to modify at least some of them. To do this we must first obtain a base configuration handle.</p>
<div class="fragment"><div class="line"><a class="code" href="group__Base.html#gacaedd5eecda28ac996abb8ff9e872c30">acc_base_configuration_t</a> base_configuration;</div><div class="line"></div><div class="line">base_configuration = <a class="code" href="group__Distance__Peak.html#ga5d78f25d507796741af42668640a4edd">acc_detector_distance_peak_get_base_configuration</a>(distance_configuration);</div><div class="line"></div><div class="line"><span class="keywordflow">if</span> (base_configuration == NULL) {</div><div class="line"> <span class="comment">/* Handle error */</span></div><div class="line">}</div></div><!-- fragment --><p>Using the base configuration handle, we can use functions to set individual configuration parameters such as the sweep range and frequency.</p>
<div class="fragment"><div class="line"><span class="comment">// Set sweep start and length</span></div><div class="line"><a class="code" href="group__Base.html#ga090e344c1df5735de164ce259dc6ee4f">acc_base_configuration_requested_start_set</a>(base_configuration, 0.2);</div><div class="line"><a class="code" href="group__Base.html#ga393b7f584caa10f60e6cb8ad55049a5a">acc_base_configuration_requested_length_set</a>(base_configuration, 0.4);</div></div><!-- fragment --><p>See <a class="el" href="acc__detector__distance__peak_8h.html">acc_detector_distance_peak.h</a> and <a class="el" href="acc__base__configuration_8h.html">acc_base_configuration.h</a> for a more complete explanation of the configuration parameters.</p>
<h3>Profiles</h3>
<p>The services and detectors support profiles with different configuration of emission in the sensor. The different profiles provide an option to configure the wavelet length and optimize on either depth resolution or radar loop gain. More information regarding profiles can be read in the <a href="https://acconeer-python-exploration.readthedocs.io/en/latest/sensor_introduction.html">sensor introduction document</a>.</p>
<div class="image">
<img src="fig_distance_resolution.png" alt="fig_distance_resolution.png"/>
</div>
<p>The figure above shows the envelope signal of the same objects with two different profiles, one with short wavelet and one with longer.</p>
<p>The distance peak detector supports 5 different profiles which are defined in <a class="el" href="acc__service_8h.html">acc_service.h</a>. Profile 1 has the shortest wavelet and should be used in applications which aim to see multiple objects or with short distance to the object. Profiles with higher numbers have longer wavelet and are more suitable to use in applications which aim to see objects with weak reflection or objects further away from the sensor. The highest profiles, 4 and 5, are optimized for maximum radar loop gain which leads to lower precision in the distance estimate.</p>
<p>Profiles can be configured by the application by using a set function in the detector api. The default profile is ACC_SERVICE_PROFILE_2.</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> <a class="code" href="group__Distance__Peak.html#ga15dae124f4ee57657df1c310187c2f6b">acc_detector_distance_peak_service_profile_set</a>(<a class="code" href="group__Distance__Peak.html#ga3d747e79d0b7aca215d412c2ca578bd0">acc_detector_distance_peak_configuration_t</a> configuration,</div><div class="line">                                                    <a class="code" href="group__Generic.html#gaa281da2c8fcd709b60cfdfe2b75b888a">acc_service_profile_t</a>                      service_profile);</div></div><!-- fragment --><h2>Absolute Amplitude</h2>
<p>The amplitude values returned by the Distance Peak Detector constitute the difference between the reflection amplitude and the threshold. The acc_detector_distance_peak_set_absolute_amplitude function can be called to configure the Distance Peak Detector to return absolute amplitude values.</p>
<div class="fragment"><div class="line">acc_detector_distance_peak_status_t detector_status;</div><div class="line"></div><div class="line"><a class="code" href="group__Distance__Peak.html#ga3d747e79d0b7aca215d412c2ca578bd0">acc_detector_distance_peak_configuration_t</a> distance_configuration;</div><div class="line"></div><div class="line">distance_configuration = <a class="code" href="group__Distance__Peak.html#ga2176a40e97e051db81b9ca5819d0e836">acc_detector_distance_peak_configuration_create</a>();</div><div class="line"></div><div class="line"><a class="code" href="group__Distance__Peak.html#gadb03f6de942299c24aefb9dce626ac26">acc_detector_distance_peak_set_absolute_amplitude</a>(distance_configuration, <span class="keyword">true</span>);</div></div><!-- fragment --><h2>Adjusting the Running Average for Better Accuracy</h2>
<p>The range and accuracy of distance measurements can be improved when running the detector using an average of multiple sweeps. This procedure may be controlled by calling the function acc_detector_distance_peak_running_average_factor_set. By setting the “factor” parameter to a value between 0-1 where 0 means that averaging is disabled. A factor 1 means that the most recent sweep has no effect on the result, which will result in that the first sweep is forever received as the result.</p>
<p>The current default value for this setting is 0.7. When measuring objects in motion this value may be decreased. To improve SNR for static objects the running average factor could be increased to a value closer to 1.</p>
<div class="fragment"><div class="line"><a class="code" href="group__Distance__Peak.html#ga3d747e79d0b7aca215d412c2ca578bd0">acc_detector_distance_peak_configuration_t</a> distance_configuration;</div><div class="line"><span class="keywordtype">float</span> factor = 0.9f;</div><div class="line"></div><div class="line">distance_configuration = <a class="code" href="group__Distance__Peak.html#ga2176a40e97e051db81b9ca5819d0e836">acc_detector_distance_peak_configuration_create</a>();</div><div class="line"></div><div class="line"><a class="code" href="group__Distance__Peak.html#gada48410a45a4d775e77992c736f19c0a">acc_detector_distance_peak_running_average_factor_set</a>(distance_configuration, factor);</div></div><!-- fragment --><h2>Threshold Mode</h2>
<h2>Fixed Threshold Mode</h2>
<p>In fixed threshold mode, you can specify the minimum amplitude level to detect. Any object reflections with an amplitude below the minimum level, will be ignored by the detector. To configure the Distance Peak Detector to operate in fixed threshold mode, call the acc_detector_distance_peak_set_threshold_mode_fixed function.</p>
<div class="fragment"><div class="line">acc_detector_distance_peak_status_t detector_status;</div><div class="line"></div><div class="line"><a class="code" href="group__Distance__Peak.html#ga3d747e79d0b7aca215d412c2ca578bd0">acc_detector_distance_peak_configuration_t</a> distance_configuration;</div><div class="line"></div><div class="line">distance_configuration = <a class="code" href="group__Distance__Peak.html#ga2176a40e97e051db81b9ca5819d0e836">acc_detector_distance_peak_configuration_create</a>();</div><div class="line"></div><div class="line">detector_status = acc_distance_set_detector_threshold_mode_fixed(distance_configuration, FIXED_THRESHOLD_VALUE);</div></div><!-- fragment --><h2>Stationary Clutter Threshold Mode</h2>
<p>The client can choose to use a fixed threshold as described above or use the “stationary clutter estimated threshold”. In “stationary clutter estimated threshold” mode, first the detector records background reflections from stationary objects in the environment surrounding the sensor. A threshold varying with distance is then calculated, so that the amplitude of the reflections from the stationary objects will be located below the threshold level at the distances where the objects are located. At distances with no stationary clutter, the threshold level will be lower. To set up a detector in this mode call the acc_detector_distance_peak_threshold_estimation_update function.</p>
<p>You are recommended to use at least 50 updates with background reflections containing stationary clutter before using the Distance Peak Detector.</p>
<p>A new threshold estimation should be performed if significant changes were made in the sensor’s surrounding environment. To reset the Distance Peak Detector to empty state, please call the acc_detector_distance_peak_threshold_estimation_reset function. Then update the Distance Peak Detector for the new environment using the acc_detector_distance_peak_threshold_estimation_update function.</p>
<div class="fragment"><div class="line">acc_detector_distance_peak_status_t detector_status;</div><div class="line"></div><div class="line">detector_status = <a class="code" href="group__Distance__Peak.html#gace179eaaabc79e7a3fb81df5e7ddace4">acc_detector_distance_peak_threshold_estimation_update</a>(distance_configuration, 100, metadata.<a class="code" href="structacc__detector__distance__peak__metadata__t.html#a647246a8a4b67d4c88d07bbdcd522756">start_m</a>, metadata.<a class="code" href="structacc__detector__distance__peak__metadata__t.html#a647246a8a4b67d4c88d07bbdcd522756">start_m</a> + metadata.<a class="code" href="structacc__detector__distance__peak__metadata__t.html#a0b30220d3f3e1bc88cf5d4cea8f2e9a9">length_m</a>);</div></div><!-- fragment --><p>It is possible to control the sensitivity and false detection rate of the Distance Peak Detector in estimated threshold mode. With high sensitivity, the detector is more likely to make false detections, e.g. interpret noise as an object. At the same time, the number of missed detections is low. With low sensitivity, the number of missed detections is likely to increase, whereas false detections are likely to decrease.</p>
<p>The sensitivity of the detector is set when calling the acc_detector_distance_peak_set_sensitivity function. This function takes a sensitivity parameter in the range between 0 and 1, where the 0 represents the lowest sensitivity and 1 the highest. The function is optional but must be called before before activating the detector.</p>
<h1>Measure Distances</h1>
<h2>Creating and Activating the Distance Peak Detector</h2>
<p>After the detector configuration has been prepared and populated with desired configuration parameters, the actual Distance Peak instance must be created. During the creation step all configuration parameters are validated and the resources needed by RSS are reserved. This means that if the creation step is successful, we can be sure that it is possible to activate the detector and get data from the sensor (unless there is some unexpected hardware error).</p>
<div class="fragment"><div class="line"><a class="code" href="group__Distance__Peak.html#ga1c4bbcd8dbbfaed9e8f9dff8e75bd5bd">acc_detector_distance_peak_handle_t</a> handle = <a class="code" href="group__Distance__Peak.html#ga35fece98044fdcedaef2305d30fa561a">acc_detector_distance_peak_create</a>(distance_configuration);</div></div><!-- fragment --><p>When the service is created, it is possible to fetch metadata from the detector</p>
<div class="fragment"><div class="line"><a class="code" href="structacc__detector__distance__peak__metadata__t.html">acc_detector_distance_peak_metadata_t</a>   metadata;</div><div class="line"></div><div class="line"><a class="code" href="group__Distance__Peak.html#ga72746c917b7cacf7d3b97bda2265a53f">acc_detector_distance_peak_get_metadata</a>(handle, &amp;metadata);</div><div class="line"></div><div class="line"><span class="keywordtype">float</span> start_m = metadata.<a class="code" href="structacc__detector__distance__peak__metadata__t.html#a647246a8a4b67d4c88d07bbdcd522756">start_m</a>;</div><div class="line"><span class="keywordtype">float</span> end_m = metadata.<a class="code" href="structacc__detector__distance__peak__metadata__t.html#a647246a8a4b67d4c88d07bbdcd522756">start_m</a> + metadata.<a class="code" href="structacc__detector__distance__peak__metadata__t.html#a0b30220d3f3e1bc88cf5d4cea8f2e9a9">length_m</a>;</div></div><!-- fragment --><p>To activate the detector call the acc_detector_distance_peak_activate function. Now the detector is producing detector data which might be retrieved by calling the acc_detector_distance_peak_get_next function.</p>
<div class="fragment"><div class="line">detector_status = <a class="code" href="group__Distance__Peak.html#ga6acc618b4411820011caa01461abcbc4">acc_detector_distance_peak_activate</a>(handle);</div><div class="line"></div><div class="line"><span class="keywordflow">if</span> (detector_status != ACC_DETECTOR_DISTANCE_PEAK_STATUS_SUCCESS) {</div><div class="line"><span class="comment">/* Handle error */</span></div><div class="line">}</div></div><!-- fragment --><h2>Getting Detection Results</h2>
<p>When the detector has been created and activated the detections results may be retrieved by calling the acc_detector_distance_peak_get_next function.</p>
<div class="fragment"><div class="line"><a class="code" href="group__Distance__Peak.html#ga3d747e79d0b7aca215d412c2ca578bd0">acc_detector_distance_peak_configuration_t</a> distance_configuration;</div><div class="line"><a class="code" href="group__Distance__Peak.html#ga1c4bbcd8dbbfaed9e8f9dff8e75bd5bd">acc_detector_distance_peak_handle_t</a>        handle;</div><div class="line">acc_detector_distance_peak_status_t        detector_status;</div><div class="line">uint_fast16_t                              reflection_count = 10;</div><div class="line"><a class="code" href="structacc__detector__distance__peak__reflection__t.html">acc_detector_distance_peak_reflection_t</a>    reflections[reflection_count];</div><div class="line"></div><div class="line">distance_configuration = <a class="code" href="group__Distance__Peak.html#ga2176a40e97e051db81b9ca5819d0e836">acc_detector_distance_peak_configuration_create</a>();</div><div class="line"></div><div class="line">handle = <a class="code" href="group__Distance__Peak.html#ga35fece98044fdcedaef2305d30fa561a">acc_detector_distance_peak_create</a>(distance_configuration);</div><div class="line"></div><div class="line">detector_status = <a class="code" href="group__Distance__Peak.html#ga6acc618b4411820011caa01461abcbc4">acc_detector_distance_peak_activate</a>(handle);</div><div class="line"></div><div class="line">detector_status = <a class="code" href="group__Distance__Peak.html#ga067d3d45df1a1e9c55a611adcf1c8cf0">acc_detector_distance_peak_get_next</a>(handle, reflections, &amp;reflection_count, &amp;result_info);</div></div><!-- fragment --><p>To get the actual distances, we must start by allocating memory for an array of type <a class="el" href="structacc__detector__distance__peak__reflection__t.html" title="Reflection struct for the distance detector reflections. ">acc_detector_distance_peak_reflection_t</a>, for storing distance estimations. In the example above, this array is allocated on the stack. Then we can call acc_detector_distance_peak_get_next to fill the array with distances and amplitudes for such reflections, which have been detected as objects by the Distance Peak Detector.</p>
<h1>Deactivating and Destroying the Distance Peak Detector</h1>
<p>To release the memory resources allocated by the Distance Peak Detector, please call the acc_detector_distance_peak_deactivate function followed by the acc_detector_distance_peak_destroy function and finally by calling the acc_detector_distance_peak_configuration_destroy function. Do this when you have reached the point where you do not need to use the detector anymore.</p>
<div class="fragment"><div class="line">detector_status = <a class="code" href="group__Distance__Peak.html#ga92eb1892440a8fb3772fad465235f2bc">acc_detector_distance_peak_deactivate</a>(handle);</div><div class="line"><a class="code" href="group__Distance__Peak.html#ga0a4e15af6dc3ecd1acb109f405770ba0">acc_detector_distance_peak_destroy</a>(&amp;handle);</div><div class="line"><a class="code" href="group__Distance__Peak.html#ga63184e020872fab10f8561323b890358">acc_detector_distance_peak_configuration_destroy</a>(&amp;distance_configuration);</div></div><!-- fragment --> </div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="navelem"><a class="el" href="md__home_ai_jenkins_workspace_sw-main_0D2_doc_user_guides_rss_user_guide_main.html">User guides</a></li>
    <li class="footer">Generated on Mon Dec 2 2019 09:40:46 for Acconeer API by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.13 </li>
  </ul>
</div>
</body>
</html>
